Skip to content

fix(db): make concurrent first-run database setup safe - #49

Merged
ChristopherDownie merged 1 commit into
mainfrom
fix/sqlite-build-race
Oct 15, 2026
Merged

ChristopherDownie merged 1 commit into
mainfrom
fix/sqlite-build-race

Conversation

@ChristopherDownie

Copy link
Copy Markdown
Contributor

Fixes the intermittent SQLITE_BUSY: database is locked failure in pnpm build on CI (example run, seen on #48, which doesn't touch the database).

Cause

apps/web/src/db/index.ts opens data/journal.db when the module is imported. During next build, several worker processes import route modules at the same time, so on a fresh checkout they all create the file, switch it to WAL and run the bootstrap at once. SQLite refuses some of those lock upgrades right away instead of calling the busy handler. Switching a rollback-journal file to WAL is the common case, which is why the error came about 0.5s into "Collecting page data" rather than after the 5s busy timeout.

Reproduced locally by running the bootstrap statements from 8 to 16 processes at once against an empty data dir: 12 of 20 rounds failed at 8 processes, and every failure was PRAGMA journal_mode = WAL.

Fix

Setup moves into openJournalDatabase() in db/bootstrap.ts:

  • The WAL switch and the schema bootstrap retry SQLITE_BUSY with a short jittered backoff, up to 15 seconds.
  • BOOTSTRAP_SQL and every additive column check and ALTER TABLE run in one BEGIN IMMEDIATE transaction. Before, several checks ran outside a transaction, so two processes upgrading the same database could both see a column as missing and both try to add it.

The db export and runtime behavior are unchanged, and a single process succeeds on the first attempt as before. I kept the build opening the database rather than skipping setup when NEXT_PHASE === "phase-production-build". Skipping would leave db without a ready schema at build time, and with the retries the build no longer depends on timing anyway.

Test

apps/web/tests/db-concurrent-init.test.ts starts 12 Node processes that load the real bootstrap module and open the same database at the same moment. It covers three fresh databases and one legacy rollback-journal database that is missing the additive columns. It then checks that the database is in WAL mode, passes the integrity check, has the upgraded columns and the seeded folders. With the retries turned off, 3 of the 4 cases fail with SQLITE_BUSY. With them on, the test passed 6 runs in a row.

Checks run locally

pnpm install --frozen-lockfile, pnpm format:check, pnpm typecheck, pnpm test (64 files, 607 tests), node scripts/check-licenses.mjs, pnpm -r --filter "./packages/*" build and pnpm build from a fresh data dir all pass.

`next build` imports route modules from several worker processes at once,
and each one opens data/journal.db at import time. On a fresh checkout
those processes race to create the file, switch it to WAL and run the
bootstrap. SQLite refuses some of those lock upgrades immediately
(switching a rollback-journal file to WAL is the common one) without
calling the busy handler, so the build failed intermittently with
SQLITE_BUSY about half a second into "Collecting page data".

Setup now lives in openJournalDatabase() in db/bootstrap.ts:
- the WAL switch and the schema bootstrap retry SQLITE_BUSY with a short
  jittered backoff, up to 15 seconds;
- BOOTSTRAP_SQL and every additive column check and ALTER run in one
  BEGIN IMMEDIATE transaction, so two processes can no longer both see a
  column as missing and both try to add it.

The `db` export and runtime behavior are unchanged; a single process
succeeds on the first attempt as before.

The new test starts 12 Node processes that load the real bootstrap module
and open the same fresh (or legacy rollback-journal) database at the
same moment. Without the retries it fails with SQLITE_BUSY in most
batches.
@ChristopherDownie
ChristopherDownie merged commit 5cc03a5 into main Oct 15, 2026
1 check passed
@ChristopherDownie
ChristopherDownie deleted the fix/sqlite-build-race branch October 28, 2026 16:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant